Released June, 1996 by Mark Womack and Patrick Bores
Code Library written by Mark Womack
Introduction
Have you ever noticed that there isn't an effective way to transfer color information from one program to another without resorting to writing down the actual values of a color and then typing them back in where you want them? It's annoying to say the least. Especially if you want to move or keep track of a number of colors. Also, if the information could be moved from one application to another, programs could work together better and in a more integrated fashion.
At least that's what we figured. Mark is the author of ColorSieve, a popular freeware utility that helps C, Pascal, and HTML programmers look at and manipulate color information. Patrick is the author of WebColor, a popular sharware application that helps HTML authors create web pages with custom colors defined for the background as well as the various types of links (as well as other neat features). We felt that our programs could work together really well if they could communicate the color information back and forth.
So, we created the Scrap Color clipboard format and supporting code library. We will be integrating this functionality into our programs, and we hope that others will do so as well. With the supporting code library written, it is a snap to integrate and call. Plus, we are placing the format and code library in the public domain. It's free to use as you like with no copyrights or licensing fees. You don't even have to mention it in your about box.
We hope that this format can become a standard to communicate color information between applications by using the clipboard. That will only happen if people start to use it in their applications, both commercial and shareware. So, please take a look at the rest of this document and the code library. We hope that you can use it!
Clipboard Format
The format of the Scrap Color data was designed with more than just our applications in mind. It is meant to be a more general solution for transfering color information.
The format supports the RGB, HSL, HSV, and CMY color models. These are the color models currently supported by Apple's Color Picker manager.
The format also supports more than one color being saved into the format. Also, the colors don't have to all be in one color model. They can be mixed. So, a program could place a whole row of colors into the clipboard, some of them being RGB and some of them being CMY or any other color model.
The following describes the Scrap Color format in detail. It is described so that if you have to write your own code to deal with the format, you'll know what to look for. However, we strongly urge you to use the code library that accompanied this read me. It is a stable, tested reference that already supports the format. Why re-writeit?
Here's a picture of what the ScrapColor format looks like:
--------------------
| Version | unsigned short (2 bytes)
--------------------
| Number of Colors | unsigned short (2 bytes)
--------------------
| Color 1 | ScrapColorData (8 bytes)
--------------------
| Color 2 | ScrapColorData (8 bytes)
--------------------
...
(ScrapColorData is repeated for number of colors)
It is basically an array of ScrapColorData with a count as the first short so you know how many colors are stored in the clipboard. The version info is used in case the format is changed in the future. Old libraries will realize they can't read the new format, and old libraries will be able to convert the old structure. It will only be incremented if the format actually changes. A ScrapColorData structure looks like this:
--------------------
| The Color's Model| short (2 bytes)
--------------------
| The Color's Data | ColorData (6 bytes)
--------------------
This structure is basically a tag to let you know what model the following data is stored as. The data is stored in a ColorData structure, and it looks like this:
--------------------
| Value 1 of Color | SmallFract (2 bytes)
--------------------
| Value 2 of Color | SmallFract (2 bytes)
--------------------
| Value 3 of Color | SmallFract (2 bytes)
--------------------
The SmallFract type is an unsigned short. It is used by all the color structures defined in the Color Picker Manager. The ColorData structure is a generic type that can store any values of the supported color models. Since they are all the same size, it makes it very convienent.
Supporting Code Library
The code library is meant to buffer programmers from having to program the nitty-gritty details of the Scrap Color clipboard format. It also provides a stable reference that everyone can use instead of having to re-invent the wheel each time.
Currently, even though the Scrap Color format supports multiple colors, the library only defines routines to get and put single colors. Going the next step and creating routines to get and put whole arrays of colors is fairly simple, in fact a future version of the library will have these routines. But to meet time contraints we chose to release the library with single color routines.
The routines can be broken into three classes: Getting, Putting, Converting. The Getting and Putting classes each have routines that support generic color data and routines that support specific color models.
GetColorFromScrap returns a ColorData structure and a color model descriptor. This information is taken directly from the clipboard. This routine makes no attempt to convert the data into any specific color model.
GetRGBColorFromScrap does just what it says. It returns the color data in the clipboard as an RGBColor. If the color data is stored in a different format than RGB, a conversion is performed to change it into RGB format.
GetHSLColorFromScrap does just what it says. It returns the color data in the clipboard as an HSLColor. If the color data is stored in a different format than HSL, a conversion is performed to change it into HSL format.
GetHSVColorFromScrap does just what it says. It returns the color data in the clipboard as an HSVColor. If the color data is stored in a different format than HSV, a conversion is performed to change it into HSV format.
GetCMYColorFromScrap does just what it says. It returns the color data in the clipboard as an CMYColor. If the color data is stored in a different format than CMY, a conversion is performed to change it into CMY format.
Putting
pascal OSErr PutColorIntoScrap(const ColorData* colorData, const short colorModel);
PutColorIntoScrap takes a ColorData structure and a color model descriptor and places them into the clipboard. It does not call ZeroScrap(), so the Scrap Color data type will coexist with any other data types that are currently stored in the clipboard. If you don't want any other types on the clipbord you must call ZeroScrap() yourself before calling PutColorIntoScrap().
PutRGBColorIntoScrap takes an RGBColor places it into the clipboard. It fills in the correct color model descriptor automatically. It does not call ZeroScrap(), so the Scrap Color data type will coexist with any other data types that are currently stored in the clipboard. If you don't want any other types on the clipboard you must call ZeroScrap() yourself before calling PutColorIntoScrap().
PutHSLColorIntoScrap takes an HSLColor places it into the clipboard. It fills in the correct color model descriptor automatically. It does not call ZeroScrap(), so the Scrap Color data type will coexist with any other data types that are currently stored in the clipboard. If you don't want any other types on the clipboard you must call ZeroScrap() yourself before calling PutColorIntoScrap().
PutHSVColorIntoScrap takes an HSVColor places it into the clipboard. It fills in the correct color model descriptor automatically. It does not call ZeroScrap(), so the Scrap Color data type will coexist with any other data types that are currently stored in the clipboard. If you don't want any other types on the clipboard you must call ZeroScrap() yourself before calling PutColorIntoScrap().
PutCMYColorIntoScrap takes an CMYColor places it into the clipboard. It fills in the correct color model descriptor automatically. It does not call ZeroScrap(), so the Scrap Color data type will coexist with any other data types that are currently stored in the clipboard. If you don't want any other types on the clipboard you must call ZeroScrap() yourself before calling PutColorIntoScrap().
Converting
pascal OSErr ConvertColor(const ColorData* oldColor, const short oldModel, ColorData* newColor, const short newModel);
ConvertColor is a convienent routine to convert color data from one color model to another. This is the routine used by the library to perform conversions when needed. Old color data is passed in with a color model descriptor indicating the model it is in and a color model descriptor describing the model you want it converted to. The color data is returned in a different ColorData parameter. Since the ColorData structure is the same size as the supported color structures, you can, if you want, coerce those structures to a ColorData pointer. Also, you can pass the same pointer to the oldColor and newColor parameters to perform an in-place conversion.
Demo Application
The demo application that is shipped with the code library is a very simple example of how to use the code library. It let's you put values from the color picker into clipboard. It also watches the clipboard and when it senses that the clipboard has changed, it trys to get Scrap Color data from it. If it succeeds, it displays the values it found in the color model the data was stored in.
Other Languages
Right now the code library is in C, but all the routines are Pascal compatible. We would be more than happy to include a Pascal version of these routines in a future package, or even a Pascal compatible library file. If there's a Pascal programmer out there that wants to do it and then send us the result, we'll give appropriate credit. The more the merrier.
Miscellaneous
The values displayed are sometimes off, especially if you use the Apple Color Picker. This has something to do with the display code, not the Scrap Color format or code library. The exact values returned from the color picker are used when putting and getting data.
Disclaimer & License for use
The Scrap Color format and the supporting code library are placed in the public domain for the benefit of all. Again, we hope that this format will become a standard for communicating color information between applications via the clipboard. You are free to use it as you wish. We only ask that if you change the format, please change the data type from 'sCLR' to something new so there is no confusion.
This software is offered 'as is'. The authors are not liable for any damages resulting from usage of this software, bugs and defects in this software, or any other problems you might encounter. By including it in any software you create, you accept these terms.
Contacts & Updates
There is an email address, mailing list, and web page for Scrap Color.
The email address is <ScrapColor@aol.com>. If you have any questions, find a program you wish used Scrap Color, or write a program that uses Scrap Color, please drop us a line!
We will be maintaining a mailing list of people interested in updates and developments regarding Scrap Color. If you'd like to be included on this mailing list, please sent a message to the Scrap Color address.
The web page for Scrap Color is <http://members.aol.com/scrapcolor/scrapcolor.html>. From here you will be able to learn about and download the latest versions of the Scrap Color format and source library.
If you use Scrap Color in your application, let us know at the Scrap Color email address. Give us a link and we'll add it to the Scrap Color web page!
Programs that use Scrap Color
There are currently only two programs that support or will support the Scrap Color format. We'd really like to see this list grow!
ColorSieve 1.2 - Not yet released, current version 1.1.
